\chapter{Environment}
\label{chap-environment}

\section{Introduction}

Translating a \commonlisp{} program from source code into an abstract
syntax tree is done in constant interaction with an
\emph{environment}.  The \hs{} stipulates%
\footnote{See Section 3.2.1 of the \hs{}.}
that there are four different environments that are relevant to
compilation:

\begin{itemize}
\item The \emph{startup environment}.  This environment is the global
  environment of the \commonlisp{} system when the compiler was
  invoked.
\item The \emph{compilation environment}.  This environment is the
  local environment in which forms are compiled.  It is also the
  environment that is passed to macro expanders.
\item The \emph{evaluation environment}.  According to the \hs{}, this
  environment is ``a run-time environment in which macro expanders and
  code specified by \texttt{eval-when} to be evaluated are
  evaluated''. 
\item The \emph{run-time environment}.  This environment is used when
  the resulting compiled program is executed.
\end{itemize}

The \hs{} does not specify how environments are represented, and there
is no specified protocol for manipulating environments.  As a result,
each implementation has its own representation and its own protocols. 

\sysname{} uses an external library called \emph{Trucler} for
representing the compile-time environment.

When \sysname{} is asked to convert a form to an abstract syntax tree,
client code must supply an object that represents the startup
environment.  During the conversion process, \sysname{} will call the
functions documented in section 4.2 of the Trucler documentation to
augment the startup environment with information introduced by binding
forms to create an augmented compilation environment.  To determine
the meaning of the program elements in the form to be converted,
\sysname{} will call the functions documented in section 3.1 of the
Trucler documentation.

Client code must supply methods on the functions in section 4.2 of the
Trucler documentation to augment the environment and return the
resulting environment.  Client code must also supply methods on the
functions in section 3.1 of the Trucler documentation that will query
the environment (whether the startup environment or the augmented
environment) and return the relevant information to \sysname{}.

It might seem that \sysname{} could represent the \emph{local part} of
the environment (i.e., the part of the environment that is temporarily
introduced when nested forms are compiled) in whatever way it pleases,
but this is not the case.  The reason is that the full environment
must be passed as an argument to macro expanders that are defined in
the startup environment, and those macro expanders are implementation
specific.  It is also not possible for \sysname{} to define its own
version of \texttt{macroexpand}, because a globally defined
implementation-specific macro expander may call the
implementation-specific version of \texttt{macroexpand} which would
fail if given an environment other than the one defined by the
implementation. 
%%  LocalWords:  startup expanders expander subclasses
